API Reference
通用错误响应
| 参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| code | integer | 是 | 错误码 |
| message | string | 是 | 错误信息 |
响应示例:
{
"code": 3,
"message": "empty key_id"
}
错误码
| 错误码 | 说明 |
|---|---|
| 3 | 参数错误 |
| 13 | 内部服务器错误 |
请求签名
为了保证 API 的安全调用, MPC-KMS 网关会对每个 API 请求通过签名 (Signature) 进行身份验证. 在调用 API 时必须在 HTTP 请求中增加 Authorization 的 Header 来包含签名 (Signature) 信息, 表明该消息已被授权.
Authorization 字段计算方法
计算方法
Authorization = "MPC-KMS" + AccessKeyId + ":" + Signature
Signature = base64(hmac-sha256(AccessKeySecret,
VERB + "\n"
+ Content-SHA256 + "\n"
+ Content-Type + "\n"
+ Date))
参数
| 参数 | 是否必选 | 示例值 | 说明 |
|---|---|---|---|
| AccessKeyId | 是 | LTAI4FixJvEPgvZ6g5cC**** | 用户的 AccessKeyId |
| AccessKeySecret | 是 | OtxrzxIsfpFjA7Sw**8Bw21TLhquhboDYROV | 用户的 AccessKeySecret |
| VERB | 是 | POST | HTTP 请求的 Method, 主要有 PUT/GET/POST/HEAD/DELETE 等 |
| \n | 否 | \n | 换行符 |
| Content-SHA256 | 否 | eB5eJF1ptWaXm4bijSPyxw== | 请求内容数据的 SHA256 值, 对消息内容（不包括头部）计算 SHA256 值获得 256 比特位数字,对该数字进行 base64 编码得出 |
| Content-Type | 否 | application/json | 请求内容的类型,也可以为空 |
| Date | 是 | Thu, 11 Nov 2021 14:16:38 GMT | 此次操作的时间, Date 必须为 GMT 格式且不能为空. (如果请求中的 Date 时间与 MPC-KMS 服务器的当前时间差为 15 分钟以上, MPC-KMS 将拒绝改请求, 并返回 HTTP 403 错误.) |
APIs
Cryptography
Sign
POST /api/v1/keys/{key_id}/sign
使用 key_id 关联的密钥签名
请求参数
| 参数 | 位置 | 是否必选 | 示例值 | 说明 |
|---|---|---|---|---|
| key_id | path | 是 | 28HowEifVCeJzWRr9ztXVYBoFkZ | 密钥 ID |
| Content-Type | header | 是 | application/json | 固定值: "application/json" |
| Authorization | header | 是 | 请求的签名 | |
| Date | header | 是 | Thu, 11 Nov 2021 14:16:38 GMT | 请求时间, 必须为 GMT 格式 |
Body 参数 (application/json)
| 参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| data | string | 是 | 需要签名的数据 |
| data_encoding | string | 否 | 签名数据的编码格式: PLAIN/BASE64/HEX, 默认是 PLAIN |
| approval | bool | 否 | 是否需要审批 |
返回响应 (200 Success)
| 参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| signature | string | 是 | 签名结果 (16 进制字符串) |
返回响应 (201 Create)
| 参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| task_id | string | 是 | 任务 ID |
Keys
Generate key
POST /api/v1/keys/generate
创建一个密钥
请求参数
| 参数 | 位置 | 是否必选 | 示例值 | 说明 |
|---|---|---|---|---|
| Content-Type | header | 是 | application/json | 固定值: "application/json" |
| Authorization | header | 是 | 请求的签名 | |
| Date | header | 是 | Thu, 11 Nov 2021 14:16:38 GMT | 请求时间, 必须为 GMT 格式 |
Body 参数 (application/json)
| 参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| format | object | 是 | 密钥格式 |
| >> type | string | 是 | 密钥类型 (ECC) |
| >> size | integer | 否 | 密钥大小 |
| >> curve | string | 是 | 曲线 (SECP256K1/BN256/BN381) |
| >> algo_type | string | 是 | 算法类型 (DMZ21/GG18/BLS) |
| refresh_interval | integer | 否 | 密钥刷新间隔 (小时) |
| keyshard_properties | object | 是 | 密钥分片属性 |
| >> threshold | integer | 是 | 阈值 |
| >> shard_count | integer | 是 | 分片数量 |
Body 参数示例
{
"format": {
"type": "ECC",
"size": 0,
"curve": "SECP256K1",
"algo_type": "DMZ21"
},
"refresh_interval": 0,
"keyshard_properties": {
"threshold": 1,
"shard_count": 3
}
}
返回响应 (200 Success)
| 参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| key_id | string | 是 | 密钥 ID |
| public_key | string | 是 | 公钥 |
响应示例 (200 Sucess)
{
"key_id": "28HowEifVCeJzWRr9ztXVYBoFkZ",
"public_key": "04b976ff954d0b4bfb7f6117534c514c30afcdfe89cc78d4646f553bb9571b36e8e2bf8f1c0ba190546e507b2cbcc4f30622af4dd9d338605f7e673b17e3b39407"
}
Get key detail
GET /api/v1/keys/{key_id}
获取密钥详情
请求参数
| 参数 | 位置 | 是否必选 | 示例值 | 说明 |
|---|---|---|---|---|
| key_id | path | 是 | 28HowEifVCeJzWRr9ztXVYBoFkZ | 密钥 ID |
| Authorization | header | 是 | 请求的签名 | |
| Date | header | 是 | Thu, 11 Nov 2021 14:16:38 GMT | 请求时间, 必须为 GMT 格式 |
返回响应 (200 Success)
| 参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| key_id | string | 是 | 密钥 ID |
| public_key | string | 是 | 公钥 |
| format | object | 是 | 密钥格式 |
| >> type | string | 是 | 密钥类型 (ECC) |
| >> size | integer | 否 | 密钥大小 |
| >> curve | string | 是 | 曲线 (SECP256K1/BN256/BN381) |
| >> algo_type | string | 是 | 算法类型 (DMZ21/GG18/BLS) |
| keyshard_properties | object | 是 | 密钥分片属性 |
| >> threshold | integer | 是 | 阈值 |
| >> shard_count | integer | 是 | 分片数量 |
| is_enable | bool | 是 | 是否可用 |
| updated_at | string | 是 | 最后更新日期 |
| created_at | string | 是 | 创建日期 |
| activation_date | string | 否 | 激活日期 |
| deactivation_date | string | 否 | 去激活日期 |
| destroy_date | string | 否 | 销毁日期 |
返回响应示例 (200 Success)
{
"key_id": "28HowEifVCeJzWRr9ztXVYBoFkZ",
"public_key": "04b976ff954d0b4bfb7f6117534c514c30afcdfe89cc78d4646f553bb9571b36e8e2bf8f1c0ba190546e507b2cbcc4f30622af4dd9d338605f7e673b17e3b39407",
"format": {
"type": "ECC",
"size": 0,
"curve": "SECP256K1",
"algo_type": "DMZ21"
},
"refresh_interval": 0,
"keyshard_properties": {
"threshold": 1,
"shard_count": 3
},
"is_enable": true,
"updated_at": "2022-08-24 17:10:22",
"created_at": "2022-08-26 12:07:50",
"activation_date": "2022-08-30 00:00:00",
"deactivation_date": "2022-08-31 00:00:00",
"destroy_date": "2022-08-31 14:43:18"
}
Enable a key
POST /api/v1/keys/{key_id}/enable
启用指定的密钥
请求参数
| 参数 | 位置 | 是否必选 | 示例值 | 说明 |
|---|---|---|---|---|
| key_id | path | 是 | 28HowEifVCeJzWRr9ztXVYBoFkZ | 密钥 ID |
| Authorization | header | 是 | 请求的签名 | |
| Date | header | 是 | Thu, 11 Nov 2021 14:16:38 GMT | 请求时间, 必须为 GMT 格式 |
返回响应 (200 Success)
无
Disable a key
POST /api/v1/keys/{key_id}/disable
禁用指定的密钥
请求参数
| 参数 | 位置 | 是否必选 | 示例值 | 说明 |
|---|---|---|---|---|
| key_id | path | 是 | 28HowEifVCeJzWRr9ztXVYBoFkZ | 密钥 ID |
| Authorization | header | 是 | 请求的签名 | |
| Date | header | 是 | Thu, 11 Nov 2021 14:16:38 GMT | 请求时间, 必须为 GMT 格式 |
返回响应 (200 Success)
无
Update a key
POST /api/v1/keys/{key_id}/update
更新指定的密钥
请求参数
| 参数 | 位置 | 是否必选 | 示例值 | 说明 |
|---|---|---|---|---|
| key_id | path | 是 | 28HowEifVCeJzWRr9ztXVYBoFkZ | 密钥 ID |
| Content-Type | header | 是 | application/json | 固定值: "application/json" |
| Authorization | header | 是 | 请求的签名 | |
| Date | header | 是 | Thu, 11 Nov 2021 14:16:38 GMT | 请求时间, 必须为 GMT 格式 |
Body 参数 (application/json)
| 参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| activation_date | string | 否 | 激活日期 |
| deactivation_date | string | 否 | 去激活日期 |
返回响应 (200 Success)
无
Activate a key
POST /api/v1/keys/{key_id}/activate
激活指定的密钥
请求参数
| 参数 | 位置 | 是否必选 | 示例值 | 说明 |
|---|---|---|---|---|
| key_id | path | 是 | 28HowEifVCeJzWRr9ztXVYBoFkZ | 密钥 ID |
| Authorization | header | 是 | 请求的签名 | |
| Date | header | 是 | Thu, 11 Nov 2021 14:16:38 GMT | 请求时间, 必须为 GMT 格式 |
返回响应 (200 Success)
无
Revoke a key
POST /api/v1/keys/{key_id}/revoke
撤销指定的密钥
请求参数
| 参数 | 位置 | 是否必选 | 示例值 | 说明 |
|---|---|---|---|---|
| key_id | path | 是 | 28HowEifVCeJzWRr9ztXVYBoFkZ | 密钥 ID |
| Authorization | header | 是 | 请求的签名 | |
| Date | header | 是 | Thu, 11 Nov 2021 14:16:38 GMT | 请求时间, 必须为 GMT 格式 |
返回响应 (200 Success)
无
Destroy a key
POST /api/v1/keys/{key_id}/destroy
销毁指定的密钥
请求参数
| 参数 | 位置 | 是否必选 | 示例值 | 说明 |
|---|---|---|---|---|
| key_id | path | 是 | 28HowEifVCeJzWRr9ztXVYBoFkZ | 密钥 ID |
| Authorization | header | 是 | 请求的签名 | |
| Date | header | 是 | Thu, 11 Nov 2021 14:16:38 GMT | 请求时间, 必须为 GMT 格式 |
返回响应 (200 Success)
无
Tasks
Get a task result
GET /api/v1/tasks/{task_id}
获取指定任务结果
请求参数
| 参数 | 位置 | 是否必选 | 示例值 | 说明 |
|---|---|---|---|---|
| task_id | path | 是 | cbjjfat6v8n1bai66i90 | 任务 ID |
| Authorization | header | 是 | 请求的签名 | |
| Date | header | 是 | Thu, 11 Nov 2021 14:16:38 GMT | 请求时间, 必须为 GMT 格式 |
返回响应 (200 Success)
| 参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| status | string | 是 | 任务状态 (PENDING_APPROVAl, DONE) |
| response | string | 否 | 任务响应 (具体响应数据取结于执行的任务类型) |
响应示例 (200 Success)
{
"status": "DONE",
"response": "{\"signature\":\"0xb3baa751d0a9132cfe93e4e3d5ff9075111100e3789dca219ade5a24d27e19d16b3353149da1833e9b691bb38634e8dc04469be7032132906c927d7e1a49b414730612877bc6b2810c8f202daf793d1ab0d6b5cb21d52f9e52e883859887a5d9\"}"
}